CAMS KRA Search and Verify API

The following document highlights the details of the CAMS KRA Search and Verify API.

API Description

Objective

The CAMS KRA Search and Verify API authenticates the status of a user's Know Your Customer (KYC) record by cross-referencing their Permanent Account Number (PAN) against various KYC Registration Agency (KRA) databases.

Input	Output
A unique 10-digit alphanumeric PAN	The KYC status of the customer in a JSON response, including their application status, KYC mode, address proof details, and KRA status information

API URL

https://ind-engine.thomas.hyperverge.co/v1/CAMSSearchAndVerify

API Endpoint

CAMSSearchAndVerify

Overview

The CAMS KRA Search and Verify API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Method - POST

Authentication

You need a unique pair of application ID ( appId ) and application key ( appKey ) from HyperVerge to verify your identity for accessing the API.

Headers

Header	Mandatory / Optional	Description	Input Format
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
transactionId	Mandatory	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Inputs

The following table provides the details of the parameters required for the CAMS KRA Search and Verify API's request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
pan	Mandatory	string	The unique 10-digit alphanumeric PAN	Format: 'CCCCCDDDDC' where 'C' represents a character and 'D' represents a digit	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the CAMS KRA Search and Verify API:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/CAMSSearchAndVerify' \
--header 'Content-Type: application/json' \
--header 'appID: <Enter_the_HyperVerge_appId>'\
--header 'appKey: <Enter_the_HyperVerge_appKey>'\
--header 'transactionID: <Enter_the_HyperVerge_transactionID>' \
--data-raw '{
    "pan": "<Enter_the_PAN>"
}'

Success Response

The following code snippet demonstrates a success response from the CAMS KRA Search and Verify API:

{
    "status": "success",
    "statusCode": "200",
    "result": {
        "CAMSSearchAndVerifyResponse": {
            "verifyPanResponse": {
                "panNo": "<PAN_Number>",
                "name": "<Name_Of_The_User>",
                "statusDate": "<Status_Date_in_DD-MM-YYYY_HH:MM:SS_Format>",
                "entryDate": "<Entry_Date_in_DD-MM-YYYY_HH:MM:SS_Format>",
                "modificationDate": "<Modification_Date_in_DD-MM-YYYY_HH:MM:SS_Format>",
                "updateStatus": "<Update_Status>",
                "holdDeactiveRemarks": "<Hold_Deactive_Remarks>",
                "camskra": "<CAMS_KRA_Status>",
                "cvlkra": "<CVL_KRA_Status>",
                "ndmlkra": "<NDML_KRA_Status>",
                "dotexkra": "<DOTEX_KRA_Status>",
                "karvykra": "<KARVY_KRA_Status>",
                "kfinkra": "<KFIN_KRA_Status>",
                "kycMode": "<KYC_Mode>",
                "signFlag": "<Signature_Flag>",
                "ipvFlag": "<IPV_Flag>",
                "perAddressProof": "<Permanent_Address_Proof>",
                "corAddressProof": "<Correspondence_Address_Proof>",
                "bsekra": "<BSE_KRA_Status>"
            }
        },
        "appUpdtflg": "<Application_Update_Flag>",
        "currentStatus": "<Current_Status>",
        "appStatusKra": "<Application_Status_KRA>",
        "summary": {
            "action": "<Action_Status>",
            "details": []
        }
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Success Response Details

The following table outlines the details of the success response from the CAMS KRA Search and Verify API:

Parameter	Type	Description
status	string	The status of the request
statusCode	string	The HTTP status code of the response
result	object	Container for the response data
CAMSSearchAndVerifyResponse	object	The CAMS search and verify response object
verifyPanResponse	object	The PAN verification response details
panNo	string	The 10 digit PAN of the user
name	string	The name of the PAN holder
statusDate	string	The date and time when the KYC status was last updated, displayed in DD-MM-YYYY HH:MM:SS format
entryDate	string	The date and time when the KYC was created, displayed in DD-MM-YYYY HH:MM:SS format
modificationDate	string	The date and time of the latest modification of KYC record in Parent KRA, displayed in DD-MM-YYYY HH:MM:SS format
updateStatus	string	The status of the KYC modification request. Possible values: UNDER PROCESS KYC REGISTERED ON HOLD KYC REJECTED NOT AVAILABLE KYC Validated
holdDeactiveRemarks	string	The remarks for when a new KYC process has either been put on hold or deactivated
camskra, cvlkra, ndmlkra, dotexkra, karvykra, kfinkra	string	The status of the KYC application in CAMS KRA, CVL KRA, NDML KRA, DOTEX KRA, KARVY KRA, or KFIN KRA respectively if the user's KYC data is present in the respective KRA, otherwise "Not Available"
kycMode	string	The mode of KYC used for an application. Possible values: Paper Based Normal KYC eKYC through OTP eKYC through Biometric Online KYC Aadhaar Offline KYC Digilocker
signFlag (??)	string	The signature flag indicating the signature status
ipvFlag	string	The information pertaining to whether in-person verification was done
perAddressProof	string	The document used as proof of permanent address
corAddressProof	string	The document used as proof of correspondence address
bsekra	string	The status of the KYC application in BSE KRA if the user's KYC data is present in this KRA, otherwise "Not Available"
appUpdtflg	string	This flag indicates the next steps for KYC application processing (e.g., New Application, Modify with Document)
currentStatus	string	The current status of the KYC application
appStatusKra	string	The KRA with which the PAN is associated for the KYC application
summary	object	The summary object containing action status and details
summary.action	string	The action status in the summary
summary.details	array	The array containing summary details
metaData	object	Metadata associated with the request
metaData.requestId	string	The unique identifier for the request
metaData.transactionId	string	The unique identifier for the transaction

Error Responses

The following are some error responses from the CAMS KRA Search and Verify API:

Invalid Input

{
    "status": "failure",
    "statusCode": "400",
    "message": "Invalid PAN format",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Missing/Invalid credentials

{
    "message": "Missing/Invalid credentials",
    "statusCode": 401,
    "status": "failure"
}

Invalid encrypted data

{
    "status": "failure",
    "statusCode": "500",
    "result": {
        "message": "Invalid encrypted data"
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Invalid token generation

{
    "status": "failure",
    "statusCode": "500",
    "message": "Invalid token generation",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Invalid KRA code

{
    "status": "failure",
    "statusCode": "500",
    "message": "Invalid KRA code",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Incorrect Total records count

{
    "status": "failure",
    "statusCode": "500",
    "message": "Incorrect Total records count",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Authentication Failed

{
    "status": "failure",
    "statusCode": "500",
    "message": "Authentication Failed",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Incorrect Request

{
    "status": "failure",
    "statusCode": "500",
    "message": "Incorrect Request",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Internal server error

{
    "statusCode": "500",
    "status": "failure",
    "result": {
        "message": "Internal server error"
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Meta data api failed

{
    "status": "failure",
    "statusCode": "500",
    "result": {
        "message": "Meta data api failed"
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Error Response Details

A failure or error response contains a failure status with a relevant status code and error message.
The following table lists all error responses:

Status Code	Error Message	Error Description	Error Resolution
400	Invalid Input	The 10-digit PAN is not in the CCCCCDDDDC format	Provide a valid PAN in the correct format
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values	Provide valid appId and appKey credentials in the request
500	Invalid encrypted data	Error due to inputs might be length or invalid inputs	Verify the input data format and length, ensure all required fields are properly formatted
500	Invalid token generation	CREDS invalid	Verify and provide valid credentials (appId and appKey)
500	Invalid KRA code	KRA code is invalid	Verify and provide a valid KRA code
500	Incorrect Total records count	The total records count provided in the request is incorrect	Verify and provide the correct total records count
500	Authentication Failed	The authentication process failed	Verify credentials and authentication parameters, contact the HyperVerge team if the issue persists
500	Incorrect Request	The request format or parameters are incorrect	Verify the request format and all required parameters
500	Internal Server Error	An internal server error occurred	Please check the request headers or contact the HyperVerge team for resolution
500	Meta data api failed	The metadata API call failed	Please check the request headers or contact the HyperVerge team for resolution